gridstack

What is gridstack?

Gridstack is a JavaScript library that helps you create dynamic, responsive, and draggable grid layouts. It is particularly useful for building dashboards, widgets, and other interactive web applications where users can customize the layout by dragging and resizing elements.

What are gridstack's main functionalities?

Draggable Widgets

This feature allows you to add draggable widgets to the grid. The code sample initializes a grid and adds a widget at position (0, 0) with a width and height of 2 units.

const grid = GridStack.init();
grid.addWidget('<div><div class="grid-stack-item-content">Widget 1</div></div>', {x: 0, y: 0, width: 2, height: 2});

Resizable Widgets

This feature allows you to add resizable widgets to the grid. The code sample initializes a grid and adds a resizable widget at position (1, 1) with a width and height of 2 units.

const grid = GridStack.init();
grid.addWidget('<div><div class="grid-stack-item-content">Widget 2</div></div>', {x: 1, y: 1, width: 2, height: 2, resizable: true});

Static Grid

This feature allows you to create a static grid where widgets cannot be dragged or resized. The code sample initializes a static grid and adds a widget at position (2, 2) with a width and height of 2 units.

const grid = GridStack.init({staticGrid: true});
grid.addWidget('<div><div class="grid-stack-item-content">Static Widget</div></div>', {x: 2, y: 2, width: 2, height: 2});

Saving and Loading Layouts

This feature allows you to save the current layout of the grid and load it later. The code sample demonstrates how to save the layout of a grid and then load it into another grid instance.

const grid = GridStack.init();
const layout = grid.save();
// Later, you can load the layout
const grid2 = GridStack.init();
grid2.load(layout);

Other packages similar to gridstack

muuri

Muuri is a JavaScript library for creating responsive, sortable, filterable, and draggable grid layouts. It offers more advanced sorting and filtering options compared to Gridstack but may require more configuration for basic grid functionalities.

packery

Packery is a JavaScript library for creating draggable and resizable grid layouts. It focuses on packing elements in the most efficient way possible, which can be useful for creating masonry-style layouts. However, it lacks some of the built-in features for saving and loading layouts that Gridstack offers.

interactjs

Interact.js is a JavaScript library for drag-and-drop, resizing, and multi-touch gestures. While it is more versatile and can be used for a variety of interactive elements, it requires more custom code to achieve the same grid functionalities that Gridstack provides out of the box.

README

gridstack.js

gridstack.js is a mobile-friendly Javascript library for dashboard layout and creation. Making a drag-and-drop, multi-column dashboard has never been easier. gridstack.js allows you to build draggable, responsive bootstrap v3-friendly layouts. It also works great with knockout.js, angular.js, ember.

Join gridstack.js on Slack: https://gridstackjs.troolee.com

Table of Contents generated with DocToc

• gridstack.js News
• Demo and examples
• Usage
  • Requirements
    • Using gridstack.js with jQuery UI
  • Install
  • Basic usage
  • Migrating to v0.3.0
  • API Documentation
  • Touch devices support
  • gridstack.js for specific frameworks
  • Change grid width
  • Extra CSS
    • Different grid widths
  • Override resizable/draggable options
  • IE8 support
  • Use with require.js
• Changes
• The Team

gridstack.js News

Version 1.0 is coming! Check out the blog post here for more information: https://dylandreams.com/2017/04/26/gridstack-10-coming-soon/ and subscribe to the blog for more gridstack news and tutorials.

Demo and examples

Please visit http://gridstackjs.com for a demo or check out these examples.

Usage

Requirements

• lodash.js (>= 3.5.0, full build)
• jQuery (>= 3.1.0)

Note: You can still use underscore.js (>= 1.7.0) instead of lodash.js

Using gridstack.js with jQuery UI

• jQuery UI (>= 1.12.0). Minimum required components: Core, Widget, Mouse, Draggable, Resizable
• (Optional) jquery-ui-touch-punch for touch-based devices support

Install

• In the browser:

<link rel="stylesheet" href="gridstack.css" />
<script src="gridstack.js"></script>
<script src="gridstack.jQueryUI.js"></script>

• Using CDN:

<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.4.0/gridstack.min.css" />
<script type="text/javascript" src='//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.4.0/gridstack.min.js'></script>
<script type="text/javascript" src='//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.4.0/gridstack.jQueryUI.min.js'></script>

• Using bower:

$ bower install gridstack

• Using npm:

$ npm install gridstack

You can download files from dist directory as well.

Basic usage

<div class="grid-stack">
    <div class="grid-stack-item"
        data-gs-x="0" data-gs-y="0"
        data-gs-width="4" data-gs-height="2">
            <div class="grid-stack-item-content"></div>
    </div>
    <div class="grid-stack-item"
        data-gs-x="4" data-gs-y="0"
        data-gs-width="4" data-gs-height="4">
            <div class="grid-stack-item-content"></div>
    </div>
</div>

<script type="text/javascript">
$(function () {
    $('.grid-stack').gridstack();
});
</script>

Migrating to v0.3.0

As of v0.3.0, gridstack introduces a new plugin system. The drag'n'drop functionality has been modified to take advantage of this system. Because of this, and to avoid dependency on core code from jQuery UI, the plugin was functionality was moved to a separate file.

To ensure gridstack continues to work, either include the additional gridstack.jQueryUI.js file into your HTML or use gridstack.all.js:

<script src="gridstack.js"></script>
<script src="gridstack.jQueryUI.js"></script>

or

<script src="gridstack.all.js"></script>

We're working on implementing support for other drag'n'drop libraries through the new plugin system.

API Documentation

Documentation can be found here.

Touch devices support

Please use jQuery UI Touch Punch to make jQuery UI Draggable/Resizable working on touch-based devices.

<script src="lodash.min.js"></script>
<script src="jquery.min.js"></script>
<script src="jquery-ui.min.js"></script>
<script src="jquery.ui.touch-punch.min.js"></script>

<script src="gridstack.js"></script>

Also alwaysShowResizeHandle option may be useful:

$(function () {
    var options = {
        alwaysShowResizeHandle: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
    };
    $('.grid-stack').gridstack(options);
});

If you're still experiencing issues on touch devices please check #444

gridstack.js for specific frameworks

• AngularJS: gridstack-angular
• Rails: gridstack-js-rails
• ember: gridstack-ember

Change grid width

To change grid width (columns count), to addition to width option, CSS rules for .grid-stack-item[data-gs-width="X"] and .grid-stack-item[data-gs-x="X"] have to be changed accordingly.

For instance for 3-column grid you need to rewrite CSS to be:

.grid-stack-item[data-gs-width="3"]  { width: 100% }
.grid-stack-item[data-gs-width="2"]  { width: 66.66666667% }
.grid-stack-item[data-gs-width="1"]  { width: 33.33333333% }

.grid-stack-item[data-gs-x="2"]  { left: 66.66666667% }
.grid-stack-item[data-gs-x="1"]  { left: 33.33333333% }

For 4-column grid it should be:

.grid-stack-item[data-gs-width="4"]  { width: 100% }
.grid-stack-item[data-gs-width="3"]  { width: 75% }
.grid-stack-item[data-gs-width="2"]  { width: 50% }
.grid-stack-item[data-gs-width="1"]  { width: 25% }

.grid-stack-item[data-gs-x="3"]  { left: 75% }
.grid-stack-item[data-gs-x="2"]  { left: 50% }
.grid-stack-item[data-gs-x="1"]  { left: 25% }

and so on.

Here is a SASS code snippet which can make life easier (Thanks to @ascendantofrain, #81 and @StefanM98, #868):

.grid-stack > .grid-stack-item {

    $gridstack-columns: 12;

    @for $i from 1 through $gridstack-columns {
        &[data-gs-width='#{$i}'] { width: (100% / $gridstack-columns) * $i; }
        &[data-gs-x='#{$i}'] { left: (100% / $gridstack-columns) * $i; }
        &[data-gs-min-width='#{$i}'] { min-width: (100% / $gridstack-columns) * $i; }
        &[data-gs-max-width='#{$i}'] { max-width: (100% / $gridstack-columns) * $i; }
    }
}

Or you can include gridstack-extra.css. See below for more details.

Extra CSS

There are few extra CSS batteries in gridstack-extra.css (gridstack-extra.min.css).

Different grid widths

You can use other than 12 grid width:

<div class="grid-stack grid-stack-N">...</div>

$('.grid-stack').gridstack({width: N});

See example: 2 grids demo

Override resizable/draggable options

You can override default resizable/draggable options. For instance to enable other then bottom right resizing handle you can init gridstack like:

$('.grid-stack').gridstack({
    resizable: {
        handles: 'e, se, s, sw, w'
    }
});

Note: It's not recommended to enable nw, n, ne resizing handles. Their behaviour may be unexpected.

IE8 support

Support of IE8 is quite limited and is not a goal at this time. As far as IE8 doesn't support DOM Level 2 I cannot manipulate with CSS stylesheet dynamically. As a workaround you can do the following:

• Create gridstack-ie8.css for your configuration (sample for grid with cell height of 60px can be found here).
• Include this CSS:

<!--[if lt IE 9]>
<link rel="stylesheet" href="gridstack-ie8.css"/>
<![endif]-->

• You can use this python script to generate such kind of CSS:

#!/usr/bin/env python

height = 60
margin = 20
N = 100

print '.grid-stack > .grid-stack-item { min-height: %(height)spx }' % {'height': height}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-height="%(index)s"] { height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-min-height="%(index)s"] { min-height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * (i + 1) + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-max-height="%(index)s"] { max-height: %(height)spx }' % {'index': i + 1, 'height': h}

for i in range(N):
	h = height * i + margin * i
	print '.grid-stack > .grid-stack-item[data-gs-y="%(index)s"] { top: %(height)spx }' % {'index': i , 'height': h}

There are at least two more issues with gridstack in IE8 with jQueryUI resizable (it seems it doesn't work) and droppable. If you have any suggestions about support of IE8 you are welcome here: https://github.com/gridstack/gridstack.js/issues/76

Use with require.js

If you're using require.js and a single file jQueryUI please check out this Stackoverflow question to get it working properly.

Changes

View our change log here.

The Team

gridstack.js is currently maintained by Pavel Reznikov and Dylan Weiss. We appreciate all contributors for help.